Fix workflow catalog table and revise documentation by dgruano · Pull Request #3 · cbib/SpaceBlocks

dgruano · 2026-08-13T12:53:46Z

What & why

The Snakemake workflow catalog automatically parses the config.schema.yaml to build a parameter table. However, our current release breaks the table in the middle:

This happens right after the description field of atera parameters. Indeed, the problem is caused by the block chomping indicator (i.e. the little > before the long, multiline description). Starting the description with > leaves a trailing newline character that is parsed by snakemake inside the table, which breaks the formatting. Instead, >- should fix the parsing. We won't know for sure until we merge to main and release to the catalog, but should work.

Otherwise, I also include small doc changes that fix typos or improve readability. Feel free to chip in.

Opening as a stacked PR onto #2 and leaving it as a draft for now, as I may add new modifications

Validation

mkdocs build --strict passes, if documentation was changed

…table

Updated section titles for consistency across examples, changing 'test' to 'example' for clarity

Sergio-ote

Great additions and corrections @dgruano, we seem to be ready for a new merge to main!

Sergio-ote · 2026-08-18T17:41:45Z


 !!! note "Snakemake-catalog page"
-    The full, always-updated table of every parameter (type, default, required) is generated automatically from the schema and shown on the workflow's Snakemake-catalog page.
+    The full, always-updated table of every parameter (type, default, required) is generated automatically from the schema and shown on the workflow's [Snakemake-catalog page](https://snakemake.github.io/snakemake-workflow-catalog/docs/workflows/cbib/SpaceBlocks.html#workflow-parameters).


Suggested change

The full, always-updated table of every parameter (type, default, required) is generated automatically from the schema and shown on the workflow's [Snakemake-catalog page](https://snakemake.github.io/snakemake-workflow-catalog/docs/workflows/cbib/SpaceBlocks.html#workflow-parameters).

The full, always-updated table of every parameter (type, default, required) is generated automatically from the schema and shown on the workflow's [Snakemake-catalog page](https://snakemake.github.io/snakemake-workflow-catalog/docs/workflows/cbib/SpaceBlocks.html).

Sergio-ote · 2026-08-18T17:45:53Z

 - **`qc_sweep` rule is diagnostic only** — it never filters, clusters, or writes an h5ad.
 - **External annotation takes over.** When enabled, it becomes the primary annotation everywhere. The [Configuration](configuration.md) allows flexibility to retain all cells or remove externally unannotated ones.
- **Config-driven colours** — regions, sample metadata, and cell types, applied consistently across every plot, with a grey fallback for undefined levels. This allows precise and consitent color representations through the analyses.
+- **Config-driven colours** — regions, sample metadata, and cell types are applied consistently across every plot, with a grey fallback for undefined levels. This allows precise and consistent colour representations throughout the analyses.


Suggested change

- **Config-driven colours** — regions, sample metadata, and cell types are applied consistently across every plot, with a grey fallback for undefined levels. This allows precise and consistent colour representations throughout the analyses.

- **Config-driven colours** — regions, sample metadata, and cell type colours are applied consistently across every plot, with a grey fallback for undefined levels. This allows precise and consistent colour representations throughout the analyses.

Sergio-ote · 2026-08-18T17:47:52Z

 SpaceBlocks lets you overlay manual **region annotations** (tumour, healthy, necrosis, …) onto your samples. You draw them once in [QuPath](https://qupath.github.io/), export them as GeoJSON, and the pipeline folds them into `obs["region_annotation"]`.

-This is an **optional but recommended step** (without it every cell is `Unlabeled`) because it unlocks the region-aware analyses (neighbourhood, per-region co-occurrence, region-level pseudobulk).
+This is an **optional but recommended step** because it unlocks the region-aware analyses (neighbourhood, per-region co-occurrence, region-level pseudobulk). Without it, every cell will be `Unlabeled`.


Suggested change

This is an **optional but recommended step** because it unlocks the region-aware analyses (neighbourhood, per-region co-occurrence, region-level pseudobulk). Without it, every cell will be `Unlabeled`.

This is an **optional but recommended step** because it unlocks the region-aware analyses (neighbourhood, per-region co-occurrence, region-level pseudobulk). **Without it, every cell will be classified as `Unlabeled`**.

Sergio-ote · 2026-08-18T17:48:21Z

 | Mode | How to obtain the image |
 | --- | --- |
-| `visiumhd` / `xenium5k` (a Headblock runs) | `snakemake qupath_images` writes one image per sample under `Samples/{sample}/QuPath_image/` (a hires PNG for Visium HD, a morphology TIFF for Xenium 5K). |
+| `visiumhd` / `xenium5k` (a Headblock runs) | `snakemake qupath_images` writes one image per sample under `Samples/{sample}/QuPath_image/` (a Hi-Res PNG for Visium HD, a morphology TIFF for Xenium 5K). |


Suggested change

| `visiumhd` / `xenium5k` (a Headblock runs) | `snakemake qupath_images` writes one image per sample under `Samples/{sample}/QuPath_image/` (a Hi-Res PNG for Visium HD, a morphology TIFF for Xenium 5K). |

| `visiumhd` / `xenium5k` (a Headblock runs) | `snakemake qupath_images` writes one image per sample under `Samples/{sample}/QuPath_image/` (a high resolution PNG for Visium HD, a morphology TIFF for Xenium 5K). |

Sergio-ote · 2026-08-18T17:52:37Z

 ## Resources & retries

-No rule uses `localrule`, so nothing runs on the scheduler's head node.
+No rule uses `localrule`, so nothing runs on the scheduler's head node as long as the selected profile has configured remote execution (e.g. see `profiles/slurm`)


Suggested change

No rule uses `localrule`, so nothing runs on the scheduler's head node as long as the selected profile has configured remote execution (e.g. see `profiles/slurm`)

No rule uses `localrule`. This is particularly important when the Snakemake profile is configured for remote execution (e.g. see `profiles/slurm`), so nothing runs on the scheduler's head node.

Sergio-ote · 2026-08-18T17:58:07Z


 Every compute rule draws `mem_mb` / `runtime` / `threads` from `config["resources"]` (with a `default` fallback).

 Memory is wrapped so it **grows with the retry attempt** (`mem_mb = base × attempt`); combined with `retries: 3` in the SLURM profile, an OOM-killed job is automatically resubmitted with more RAM.


Suggested change

Memory is wrapped so it **grows with the retry attempt** (`mem_mb = base × attempt`); combined with `retries: 3` in the SLURM profile, an OOM-killed job is automatically resubmitted with more RAM.

!!! warning "Job retry triggers"

Retries are triggered by any job failure, not specifically out-of-memory errors, so jobs failing for other reasons will also be resubmitted with increased memory.

Sergio-ote · 2026-08-18T18:00:49Z

 ```

 ## Visium HD example (mouse brain)
+[comment]: <Of the four examples, two are called examples and two other are called tests. Two add the name "HeadBlock" but two other don't. We should change this for consistency>


Suggested change

[comment]: <Of the four examples, two are called examples and two other are called tests. Two add the name "HeadBlock" but two other don't. We should change this for consistency>

dgruano self-assigned this Aug 13, 2026

Base automatically changed from chore/hooks to dev August 18, 2026 14:02

Sergio-ote force-pushed the dani/docs branch from b984a7f to 46834ff Compare August 18, 2026 14:02

dgruano force-pushed the dani/docs branch from 8549010 to 319405b Compare August 18, 2026 17:07

dgruano added 4 commits August 18, 2026 19:13

docs: fix description newlines to avoid breaking automatic parameter …

5d8cf06

…table

WIP: docs: revise typos and wording

56c91c7

docs: fix typos

cef5840

docs: second revision of docs

b8b286c

dgruano force-pushed the dani/docs branch from 319405b to b8b286c Compare August 18, 2026 17:14

dgruano commented Aug 18, 2026

View reviewed changes

Comment thread docs/rules.md

dgruano commented Aug 18, 2026

View reviewed changes

Comment thread docs/demos.md Outdated

dgruano marked this pull request as ready for review August 18, 2026 17:19

dgruano requested a review from Sergio-ote August 18, 2026 17:20

dgruano and others added 2 commits August 18, 2026 19:23

docs: add link to catalogue in badge

0d39576

Standardize example section titles in demos.md

4ac0071

Updated section titles for consistency across examples, changing 'test' to 'example' for clarity

Sergio-ote approved these changes Aug 18, 2026

View reviewed changes

Sergio-ote merged commit e47990c into dev Aug 18, 2026
3 checks passed

Sergio-ote deleted the dani/docs branch August 25, 2026 10:33

dgruano mentioned this pull request Aug 28, 2026

refactor: make config paths relative to a base_path #7

Merged

8 tasks

Navigation Menu

Uh oh!

Fix workflow catalog table and revise documentation - #3

Fix workflow catalog table and revise documentation#3
Sergio-ote merged 6 commits into
devfrom
dani/docs

dgruano commented Aug 13, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Sergio-ote left a comment

Uh oh!

Sergio-ote Aug 18, 2026

Uh oh!

Sergio-ote Aug 18, 2026

Uh oh!

Sergio-ote Aug 18, 2026

Uh oh!

Sergio-ote Aug 18, 2026

Uh oh!

Sergio-ote Aug 18, 2026

Uh oh!

Sergio-ote Aug 18, 2026

Uh oh!

Sergio-ote Aug 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	The full, always-updated table of every parameter (type, default, required) is generated automatically from the schema and shown on the workflow's [Snakemake-catalog page](https://snakemake.github.io/snakemake-workflow-catalog/docs/workflows/cbib/SpaceBlocks.html#workflow-parameters).
	The full, always-updated table of every parameter (type, default, required) is generated automatically from the schema and shown on the workflow's [Snakemake-catalog page](https://snakemake.github.io/snakemake-workflow-catalog/docs/workflows/cbib/SpaceBlocks.html).

	- Config-driven colours — regions, sample metadata, and cell types are applied consistently across every plot, with a grey fallback for undefined levels. This allows precise and consistent colour representations throughout the analyses.
	- Config-driven colours — regions, sample metadata, and cell type colours are applied consistently across every plot, with a grey fallback for undefined levels. This allows precise and consistent colour representations throughout the analyses.

	This is an optional but recommended step because it unlocks the region-aware analyses (neighbourhood, per-region co-occurrence, region-level pseudobulk). Without it, every cell will be `Unlabeled`.
	This is an optional but recommended step because it unlocks the region-aware analyses (neighbourhood, per-region co-occurrence, region-level pseudobulk). Without it, every cell will be classified as `Unlabeled`.

	\| `visiumhd` / `xenium5k` (a Headblock runs) \| `snakemake qupath_images` writes one image per sample under `Samples/{sample}/QuPath_image/` (a Hi-Res PNG for Visium HD, a morphology TIFF for Xenium 5K). \|
	\| `visiumhd` / `xenium5k` (a Headblock runs) \| `snakemake qupath_images` writes one image per sample under `Samples/{sample}/QuPath_image/` (a high resolution PNG for Visium HD, a morphology TIFF for Xenium 5K). \|

	No rule uses `localrule`, so nothing runs on the scheduler's head node as long as the selected profile has configured remote execution (e.g. see `profiles/slurm`)
	No rule uses `localrule`. This is particularly important when the Snakemake profile is configured for remote execution (e.g. see `profiles/slurm`), so nothing runs on the scheduler's head node.


		Every compute rule draws `mem_mb` / `runtime` / `threads` from `config["resources"]` (with a `default` fallback).

		Memory is wrapped so it grows with the retry attempt (`mem_mb = base × attempt`); combined with `retries: 3` in the SLURM profile, an OOM-killed job is automatically resubmitted with more RAM.

+Memory is wrapped so it **grows with the retry attempt** (`mem_mb = base × attempt`); combined with `retries: 3` in the SLURM profile, an OOM-killed job is automatically resubmitted with more RAM.
+!!! warning "Job retry triggers"
+    Retries are triggered by any job failure, not specifically out-of-memory errors, so jobs failing for other reasons will also be resubmitted with increased memory.

Uh oh!

Conversation

dgruano commented Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What & why

Validation

Uh oh!

Uh oh!

Uh oh!

Sergio-ote left a comment

Choose a reason for hiding this comment

Uh oh!

Sergio-ote Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

Sergio-ote Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

Sergio-ote Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

Sergio-ote Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

Sergio-ote Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

Sergio-ote Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

Sergio-ote Aug 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dgruano commented Aug 13, 2026 •

edited

Loading